package com.za.upgradeshield;

import javax.servlet.http.HttpServletRequest;

/**
 * 自定义拦截响应构建器接口。
 * <p>
 * 用于在 Shield 拦截器命中后，动态构建返回体。用户可以通过实现该接口，
 * 实现个性化的响应格式（如统一响应包装、添加调试信息、国际化提示等）。
 * </p>
 *
 * <p>
 * Starter 中提供了一个默认实现返回 {@code Response.fail(code, message)}；
 * 用户也可以在自己的项目中通过注册 {@code @Bean ShieldResponseBuilder} 的方式进行替换。
 * </p>
 *
 * <pre>{@code
 * @Bean
 * public ShieldResponseBuilder customBuilder() {
 *     return (request, path) -> {
 *         Map<String, Object> map = new HashMap<>();
 *         map.put("code", 401);
 *         map.put("message", "该接口不允许访问：" + path);
 *         return map;
 *     };
 * }
 * }</pre>
 *
 * @author zhuosihua
 */
@FunctionalInterface
public interface ShieldResponseBuilder {

    /**
     * 构建拦截响应体的方法。
     *
     * @param request 当前的 HTTP 请求对象，便于获取 Header、参数、IP 等上下文信息
     * @param path    当前被拦截的请求路径，便于用户判断来源路径或个性化提示
     * @return 任何可以被序列化为 JSON 的对象（如 Map、POJO、自定义响应体类等）
     */
    Object build(HttpServletRequest request, String path);
}
